Style Guide rough draft #1192

wendellpiez · 2022-03-28T21:55:24Z

Committer Notes

Rough draft towards a web page addressing #1185. (PR targets develop pls tweak if wrong.)

This may have to cycle a couple of times to get the links to work, because it links to its own source.

All Submissions:

Have you selected the correct base branch per Contributing guidance?
Have you set "Allow edits and access to secrets by maintainers
"?
Have you checked to ensure there aren't other open Pull Requests for the same update/change?
Have you squashed any non-relevant commits and commit messages? [instructions]
Do all automated CI/CD checks pass?

Changes to Core Features:

Have you added an explanation of what your changes do and why you'd like us to include them? Style Guide for OSCAL Documentation #1185
Have you written new tests for your core changes, as applicable?
Have you included examples of how to use your new feature(s)?
Have you updated all OSCAL website and readme documentation affected by the changes you made? Changes to the OSCAL website can be made in the docs/content directory of your branch.

wendellpiez · 2022-03-29T20:35:38Z

@david-waltermire-nist as I noted in chat, there are (generated) files in this PR that could (should?) be removed: is there an easy way to do that?

The only files in the commit should be the new styleguide.md, its CSS oscal-styleguide.css, a copy of an image, and a slight modification to a readme that had fallen out of date.

@david-waltermire-nist

…l commits Initial dump of outline with some contents Rearranged and built out more contents and links More slight adjustments Further touchups Various continuing enhancements Rearrangment and spiffup Many more adjustments to draft style guide Pushing up missing assets (thanks @david-waltermire-nist) More touchups; pretty close to a complete draft 1 for usnistgov#1185 Repairing broken links Undoing changes to generated files

More language on rights; Clarification touchup

wendellpiez · 2022-03-30T15:17:38Z

The latest commit is about ready, so I am marking this for review.

Small/final items to come back to:

Filling in the 'reflective' link e.g. the file source (which will bounce until this is merged)
Signing with our names as authors
Making a MIDAS record and providing with self-citation (make a spinoff Issue for this)?

avdouglas-nist · 2022-03-31T20:51:49Z

Wendell, I quickly browsed through and found the following possible minor issues:

misspelled Hugo at the end of this paragraph
The styling on our web sites is enabled and limited by the back-end architecture we use to produce and maintain them, the US Web Design System, which we deliver via an implementation of Hugfo.
missing comma after OSCAL
Writing for OSCAL we must rely on our readers to distinguish what advice is clearly not appropriate or useful to them, and the same rule applies to this page.
double "be" in this paragraph
Capitalization is tricky. As a rule, a proper noun is capitalized in English, and hence a reference to a formal object (such as an OSCAL Control object or a Github Issue) should be be capitalized,
should probably be not "an issue" instead of "at issue"
The fact that other kinds of validation may be implicit, or not at issue, does not have to be explained.
probably need to remove the comma after the word "wide"
Keep in mind when writing for OSCAL that the potential audience is very wide, and includes an international general public.

galtm · 2022-04-06T23:26:32Z

docs/content/contribute/styleguide.md

+
+Capitalization is tricky. As a rule, a proper noun is capitalized in English, and hence a reference to a formal object (such as an OSCAL <q>Control</q> object or a Github <q>Issue</q>) should be capitalized, when it has its own name. Both abstractions and things that are not abstract may have names, such as the host of our web presence, which is named <q>Pages</q> (or <q>the NIST Pages site</q>). (Other examples include Avogadro's Number, the Second Law of Thermodynamics, the OSCAL Style Guide, and Markdown, a family of text encoding technologies.)
+
+But even a well-known abstraction such as <q>1 + 1 = 2</q> is not called an <q>Equation</q> (capitalized). To use capitals when referring to something by name is different from instantly or implicitly coining a new technical term out of nothing, by using capitals. To call a Github ticket an <q>Issue</q> is not incorrect if that is what Github calls it; but a ticket in another tracking system is not an <q>Issue</q> (capitalized). In an OSCAL context, even a technical term such as <q>profile resolution</q> should not be capitalized just because is used in a specialized sense.


At the end of this line, you probably meant to write "because it is used" instead of "because is used".

aj-stein-nist

This is very thorough and impressive, thanks for working on this.

This is actually difficult to review. I have some minor specific feedback, but there are some larger questions I have in relation to the strategy and approach that are not really directed at individual content items.

Is it possible we review, as a group, the outline in the comments on #1185 and discuss as a whole team what are the specific goals we want out of this document? In the issue we cite some exemplary guides (like pl.gov) and others, we want to follow, so I wonder if we can choose what key elements of those we do and do not want?

docs/README.md

aj-stein-nist · 2022-04-18T14:07:42Z

docs/content/contribute/styleguide.md

@@ -0,0 +1,324 @@
+---
+title: OSCAL Style Guide
+description: (with links) Contributors to OSCAL can save time by scanning this early.


Question: what does "(with links)" mean in this context? Is it meant to be kept in the PR?

aj-stein-nist · 2022-04-18T14:13:25Z

docs/content/contribute/styleguide.md

+
+The coverage here aims to be helpful and suggestive rather than normative. Feel free to create an [Issue on Github](https://github.com/usnistgov/OSCAL/issues/new?labels=User+Story%2C+enhancement%2C+Scope:%20Website&template=feature_request.md) to raise questions or points of discussion regarding either style (covered or not covered) or the Style Guide itself.
+
+The styling on our web sites is enabled and limited by the back-end architecture we use to produce and maintain them, the [US Web Design System](https://designsystem.digital.gov/), which we deliver via an [implementation](https://pages.nist.gov/hugo-uswds-docs/) of  [Hugo](https://gohugo.io/). See more below under [Hugo and Markdown](#hugo-and-markdown). Much of this guide assumes you are writing for a web site such as the [OSCAL web site](https://pages.nist.gov/OSCAL/) or for web-accessible resources such as `readme` documents in Github, and may be more or less applicable for other cases. Writing for OSCAL, we must rely on our readers to distinguish what advice is clearly not appropriate or useful to them, and the same rule applies to this page.


So maybe the requirements and acceptance criteria has shifted for the user story of #1185, but I interpreted the main intent to be a style guide for the content, not for presentation style with HTML and CSS. We begin looping that in here.

Is that not a separate goal?

The scope probably stretched a little however I discovered that: (a) the mechanics were not covered elsewhere, (b) they more or less had to be, among other reasons because they were sometimes (not always) implicated in matters of style; accordingly, a bare-bones treatment was judged to be in scope. Arguably a page on the mechanics could be carved out but TIASD (that is a separate discussion) raising questions of its own.

I suggest raising this as an Issue IFF it is found, shown or discovered to be a real issue for users.

aj-stein-nist · 2022-04-18T14:45:07Z

docs/content/contribute/styleguide.md

+
+### Accessibility
+
+Since materials for the web site are authored using generic encoding (Markdown) and produced with an automated production pipeline, we are able to encapsulate and manage page design within our build. This takes accessibility and accessibility compliance (such as ADA) out of the hands of authors, for the most part.


I agree this information is important, but is it relevant to the style guide? We already link to the global NIST footer about accessibility.

See above. This could arguably at some point be separated out; for now we need a stake in the ground. (Metaphor without scare quotes.) Don't think a Style Guide today should be without some level of treatment.

aj-stein-nist · 2022-04-18T14:46:01Z

docs/content/contribute/styleguide.md

+
+Please be so kind as to provide `alt` values for all images to save us effort in meeting Accessibility benchmarks. Otherwise, authors should be able to rely on the publishing process to handle technical requirements related to accessibility.
+
+At the same time, the builders of the back end support for these publications will be interested to know of any accessibility-related requirements that are not already adequately addressed.


I agree this is important, but should we not express this elsewhere?

Perhaps set aside development effort in the backlog for automated and/or manual accessibility testing?

Same as above. We should also express this elsewhere, not instead (in my view).

aj-stein-nist · 2022-04-19T03:27:59Z

docs/content/contribute/styleguide.md

+
+For example, whenever writing about <q>validation</q>, be specific as to what kind of validation is meant, since the word has both generic and specific senses.
+
+Similarly, <q>control</q> has both an OSCAL sense, and an RMF sense (Risk Management Framework as defined by NIST SP800-37); a document that uses the term specifically in one of these senses, the other, or both (when OSCAL is being used to model RMF), might indicate this.


The point made in this paragraph is excellent, and I believe Dave suggested we will apply what we quickly described as "use a specific formal noun, at least two words rule: OSCAL Control, RMF Control, but not control; XML Schema validation, OSCAL model validation, but not just validation" Can we reference that heuristic in the project? I happen to like that as it is a simple measure for these kinds of things.

I like it well enough but I think it is best as a "folk heuristic". I don't think people should be penalized or ostracized for saying "control" after they've said "OSCAL Control" six or eight times in a conversation....

aj-stein-nist · 2022-04-19T03:31:32Z

docs/content/contribute/styleguide.md

+
+Similarly, <q>control</q> has both an OSCAL sense, and an RMF sense (Risk Management Framework as defined by NIST SP800-37); a document that uses the term specifically in one of these senses, the other, or both (when OSCAL is being used to model RMF), might indicate this.
+
+Yet not every use of an overloaded term must be qualified. Various senses might be left implicit if no confusion is caused (again, considered in context). In accordance with a more general rule that plain common nouns are to be preferred over jargon, terms such as <q>control</q> or <q>profile</q> might be used without further explanation when context makes it clear enough what is meant *even if a term is also overloaded* (means other things in other contexts). Within the context of describing a processing pipeline for OSCAL profiles, <q>valid profile</q> might be taken as shorthand for <q>XML \[or JSON] document known to be valid using a \[profile] schema</q>, especially when this is stated outright at the top. The fact that other kinds of validation may be implicit, or not relevant, does not have to be explained.


I like the sentiment, but I would disagree with this statement. Is this something we want to encourage in the style guide? I defer to the greater group.

When working on our informational overview document regarding the emerging rules construct and the validation documentation in #1169, this was one of the key issues we had in discussion with community: many misunderstandings in OSCAL occur due to the use of a common noun, and we presume the audience knows which meaning of the 1/n meanings of the overloaded common noun we mean.

In view of your resistance I am making small edits on this paragraph. The advice is for me, actually (but if the shoe fits, wear it).

aj-stein-nist · 2022-04-19T03:36:22Z

docs/content/contribute/styleguide.md

+
+In general, technical terms (and even formal names) should be avoided in favor of non-technical language except when necessary for specific clarification *within the context of use* including your intended audience. For instance, a tutorial intended for beginners does not (and should not) exhaust every topic: it should be technical only as appropriate and necessary, and technical language not actually useful to understand problems or concepts at hand, can often be saved for elsewhere.
+
+Nonetheless, technical terminology is often necessary. For documents reaching non-technical audiences (or non-domain experts), this often requires offering brief definitions for terms at the head of a document, or even a glossary. Even technical audiences can be helped by a link to a specification that defines formal terms. In any case, formal terminologies can be called out and identified as such. For example, both OSCAL and RMF (Risk Management Framework) terminology may combine in a description of a use case for a new feature. In this instance a brief notice of what is meant by terms such as <q>profile</q> or <q>baseline</q> is not out of order.


Resurfacing the previous comment about acronyms, can we use this to drive our own use of the terminology page, the CSRC glossary, and a hierarchy of more general resources we ask people to rely upon? (And to be fair: I address this to the whole team.)

We can include links to glossaries / acronym pages; I have already included a couple.

aj-stein-nist · 2022-04-19T03:39:35Z

docs/content/contribute/styleguide.md

+
+In addition to maintaining web platforms, the OSCAL project publishes resources and tools through the formal NIST data publishing process, for release through NIST's [Science Data Portal](http://data.nist.gov). This is appropriate for (NIST-authored) contributions that should be indexed as scientific publications, or archived as discrete data sets.
+
+The formal review process this entails will presumably not be a problem for works the site editors are also reviewing. Mechanically, the process can be lightweight, requiring nothing more than a structured metadata record with a link to a published (web-accessible) OSCAL resource. This record is provided and maintained in NIST's metadata repository for [Management of Institutional Data Assets](https://midas.nist.gov/)). 


I do not believe MIDAS is a public resource accessible outside of NIST staff's intranet, so do we reference it? I know we should remind people there is a data management policy, but Google dorking to search for it outside of NIST intranet I struggle to find mention of it. I find a lot about another scientific project named MIDAS though.

Edited to remove the links requiring credentials. Readers will just have to follow instructions on finding them.

aj-stein-nist · 2022-04-19T03:40:27Z

docs/content/contribute/styleguide.md

+
+Even if submitting work only for the web site, NIST authors will want to be aware of NIST-specific guidance for its formal publications:
+
+- [Guidance for Authorship of Scholarly and Technical Publications](https://inet.nist.gov/adlp/directives/guidance-authorship-scholarly-technical-publications) (requires NIST authentication)


Like MIDAS, ditto re access to NIST internal resources on the intranet, unless we really deem it valuable.

Okay, but if I get slammed for removing the helpful links....!

Co-authored-by: Alexander Stein <[email protected]>

wendellpiez · 2022-04-20T19:57:32Z

@aj-stein-nist has a couple of questions/issues to float up, but not AFAIK blockers at this time. Our long-term strategy is still evolving....

wendellpiez · 2022-05-10T13:14:54Z

This has been ready and not touched. Is there a way for me to put it back into the Triage bucket? @david-waltermire-nist @aj-stein-nist

aj-stein-nist · 2022-05-10T13:19:13Z

This has been ready and not touched. Is there a way for me to put it back into the Triage bucket? @david-waltermire-nist @aj-stein-nist

I know I had initial feedback but I hadn't circled back on my review comments or how I can help after I returned because I checked #1185 and this work is slated for 1.1.0 (not 1.0.4).

That said, I definitely would like to get it in place sooner rather than later if that is possible and desirable! Let me know how I can help.

aj-stein-nist · 2023-02-10T17:34:55Z

This PR is good, but we have not revisited this work in recent sprints and it is unlikely to get merged in the next sprint, perhaps not the following. I will close the PR, but the branch will remain. We can revive once we bring the related issue back to the scope of a sprint and take it from there.

wendellpiez force-pushed the issue1185-styleguideA branch 2 times, most recently from fe0c807 to 85cfa20 Compare March 29, 2022 20:13

wendellpiez force-pushed the issue1185-styleguideA branch from 00bcbca to 3fe3536 Compare March 29, 2022 21:17

Couple of touchups thanks @galtm for suggestions;

b76c378

More language on rights; Clarification touchup

wendellpiez force-pushed the issue1185-styleguideA branch from f48656d to b76c378 Compare March 30, 2022 15:04

wendellpiez added 2 commits March 31, 2022 17:02

Addressing a few small errors (spelling/grammar) thanks @avdouglas-nist

f6f8f48

Added link to NIST citation format page

03a9a7f

galtm reviewed Apr 6, 2022

View reviewed changes

Corrected grammar providing omitted pronoun "it" thanks @galtm

982aa81

aj-stein-nist linked an issue Apr 18, 2022 that may be closed by this pull request

Style Guide for OSCAL Documentation #1185

Open

3 tasks

aj-stein-nist reviewed Apr 19, 2022

View reviewed changes

wendellpiez and others added 3 commits April 20, 2022 15:11

Addressing review comments by @aj-stein-nist thanks!

2a9ad55

Correcting relative path in readme

7657504

Co-authored-by: Alexander Stein <[email protected]>

Two words, with apologies

e6fb791

wendellpiez marked this pull request as ready for review April 20, 2022 19:55

david-waltermire force-pushed the develop branch from 6587e35 to 51741c7 Compare May 17, 2022 12:13

wendellpiez requested a review from david-waltermire as a code owner May 17, 2022 12:13

david-waltermire marked this pull request as draft June 16, 2022 17:43

david-waltermire force-pushed the develop branch from b7d376f to d8682eb Compare June 21, 2022 16:14

david-waltermire force-pushed the develop branch from 09e6eee to 7aa46b6 Compare July 13, 2022 21:30

david-waltermire force-pushed the develop branch from c4de2fe to 0a6189a Compare August 23, 2022 03:01

aj-stein-nist force-pushed the develop branch from fa5250c to e4f710c Compare October 18, 2022 18:29

david-waltermire force-pushed the develop branch from e5a3198 to a37c965 Compare October 31, 2022 20:27

aj-stein-nist force-pushed the develop branch from eff9ce3 to dd6486a Compare January 10, 2023 18:39

aj-stein-nist closed this Feb 10, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Style Guide rough draft #1192

Style Guide rough draft #1192

wendellpiez commented Mar 28, 2022 •

edited

Loading

wendellpiez commented Mar 29, 2022

wendellpiez commented Mar 30, 2022

avdouglas-nist commented Mar 31, 2022

galtm Apr 6, 2022

aj-stein-nist left a comment

aj-stein-nist Apr 18, 2022

aj-stein-nist Apr 18, 2022

wendellpiez Apr 20, 2022

aj-stein-nist Apr 18, 2022

wendellpiez Apr 20, 2022

aj-stein-nist Apr 18, 2022

wendellpiez Apr 20, 2022

aj-stein-nist Apr 19, 2022

wendellpiez Apr 20, 2022

aj-stein-nist Apr 19, 2022

wendellpiez Apr 20, 2022

aj-stein-nist Apr 19, 2022

wendellpiez Apr 20, 2022

aj-stein-nist Apr 19, 2022

wendellpiez Apr 20, 2022

aj-stein-nist Apr 19, 2022

wendellpiez Apr 20, 2022

wendellpiez commented Apr 20, 2022

wendellpiez commented May 10, 2022

aj-stein-nist commented May 10, 2022 •

edited

Loading

aj-stein-nist commented Feb 10, 2023


		Capitalization is tricky. As a rule, a proper noun is capitalized in English, and hence a reference to a formal object (such as an OSCAL <q>Control</q> object or a Github <q>Issue</q>) should be capitalized, when it has its own name. Both abstractions and things that are not abstract may have names, such as the host of our web presence, which is named <q>Pages</q> (or <q>the NIST Pages site</q>). (Other examples include Avogadro's Number, the Second Law of Thermodynamics, the OSCAL Style Guide, and Markdown, a family of text encoding technologies.)

		But even a well-known abstraction such as <q>1 + 1 = 2</q> is not called an <q>Equation</q> (capitalized). To use capitals when referring to something by name is different from instantly or implicitly coining a new technical term out of nothing, by using capitals. To call a Github ticket an <q>Issue</q> is not incorrect if that is what Github calls it; but a ticket in another tracking system is not an <q>Issue</q> (capitalized). In an OSCAL context, even a technical term such as <q>profile resolution</q> should not be capitalized just because is used in a specialized sense.


		The coverage here aims to be helpful and suggestive rather than normative. Feel free to create an [Issue on Github](https://github.com/usnistgov/OSCAL/issues/new?labels=User+Story%2C+enhancement%2C+Scope:%20Website&template=feature_request.md) to raise questions or points of discussion regarding either style (covered or not covered) or the Style Guide itself.

		The styling on our web sites is enabled and limited by the back-end architecture we use to produce and maintain them, the [US Web Design System](https://designsystem.digital.gov/), which we deliver via an [implementation](https://pages.nist.gov/hugo-uswds-docs/) of [Hugo](https://gohugo.io/). See more below under [Hugo and Markdown](#hugo-and-markdown). Much of this guide assumes you are writing for a web site such as the [OSCAL web site](https://pages.nist.gov/OSCAL/) or for web-accessible resources such as `readme` documents in Github, and may be more or less applicable for other cases. Writing for OSCAL, we must rely on our readers to distinguish what advice is clearly not appropriate or useful to them, and the same rule applies to this page.


		### Accessibility

		Since materials for the web site are authored using generic encoding (Markdown) and produced with an automated production pipeline, we are able to encapsulate and manage page design within our build. This takes accessibility and accessibility compliance (such as ADA) out of the hands of authors, for the most part.


		Please be so kind as to provide `alt` values for all images to save us effort in meeting Accessibility benchmarks. Otherwise, authors should be able to rely on the publishing process to handle technical requirements related to accessibility.

		At the same time, the builders of the back end support for these publications will be interested to know of any accessibility-related requirements that are not already adequately addressed.


		For example, whenever writing about <q>validation</q>, be specific as to what kind of validation is meant, since the word has both generic and specific senses.

		Similarly, <q>control</q> has both an OSCAL sense, and an RMF sense (Risk Management Framework as defined by NIST SP800-37); a document that uses the term specifically in one of these senses, the other, or both (when OSCAL is being used to model RMF), might indicate this.


		Similarly, <q>control</q> has both an OSCAL sense, and an RMF sense (Risk Management Framework as defined by NIST SP800-37); a document that uses the term specifically in one of these senses, the other, or both (when OSCAL is being used to model RMF), might indicate this.

		Yet not every use of an overloaded term must be qualified. Various senses might be left implicit if no confusion is caused (again, considered in context). In accordance with a more general rule that plain common nouns are to be preferred over jargon, terms such as <q>control</q> or <q>profile</q> might be used without further explanation when context makes it clear enough what is meant even if a term is also overloaded (means other things in other contexts). Within the context of describing a processing pipeline for OSCAL profiles, <q>valid profile</q> might be taken as shorthand for <q>XML \[or JSON] document known to be valid using a \[profile] schema</q>, especially when this is stated outright at the top. The fact that other kinds of validation may be implicit, or not relevant, does not have to be explained.


		In general, technical terms (and even formal names) should be avoided in favor of non-technical language except when necessary for specific clarification within the context of use including your intended audience. For instance, a tutorial intended for beginners does not (and should not) exhaust every topic: it should be technical only as appropriate and necessary, and technical language not actually useful to understand problems or concepts at hand, can often be saved for elsewhere.

		Nonetheless, technical terminology is often necessary. For documents reaching non-technical audiences (or non-domain experts), this often requires offering brief definitions for terms at the head of a document, or even a glossary. Even technical audiences can be helped by a link to a specification that defines formal terms. In any case, formal terminologies can be called out and identified as such. For example, both OSCAL and RMF (Risk Management Framework) terminology may combine in a description of a use case for a new feature. In this instance a brief notice of what is meant by terms such as <q>profile</q> or <q>baseline</q> is not out of order.


		In addition to maintaining web platforms, the OSCAL project publishes resources and tools through the formal NIST data publishing process, for release through NIST's [Science Data Portal](http://data.nist.gov). This is appropriate for (NIST-authored) contributions that should be indexed as scientific publications, or archived as discrete data sets.

		The formal review process this entails will presumably not be a problem for works the site editors are also reviewing. Mechanically, the process can be lightweight, requiring nothing more than a structured metadata record with a link to a published (web-accessible) OSCAL resource. This record is provided and maintained in NIST's metadata repository for [Management of Institutional Data Assets](https://midas.nist.gov/)).


		Even if submitting work only for the web site, NIST authors will want to be aware of NIST-specific guidance for its formal publications:

		- [Guidance for Authorship of Scholarly and Technical Publications](https://inet.nist.gov/adlp/directives/guidance-authorship-scholarly-technical-publications) (requires NIST authentication)

Style Guide rough draft #1192

Style Guide rough draft #1192

Conversation

wendellpiez commented Mar 28, 2022 • edited Loading

Committer Notes

All Submissions:

Changes to Core Features:

wendellpiez commented Mar 29, 2022

wendellpiez commented Mar 30, 2022

avdouglas-nist commented Mar 31, 2022

Choose a reason for hiding this comment

aj-stein-nist left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wendellpiez commented Apr 20, 2022

wendellpiez commented May 10, 2022

aj-stein-nist commented May 10, 2022 • edited Loading

aj-stein-nist commented Feb 10, 2023

wendellpiez commented Mar 28, 2022 •

edited

Loading

aj-stein-nist commented May 10, 2022 •

edited

Loading